home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Source Code / Libraries / Internet Config 1.2 / Internet Config / APIs / ICAPI.h next >
Encoding:
Text File  |  1995-09-25  |  24.8 KB  |  257 lines  |  [TEXT/CWIE]
  1. y on the
  2.    * exact format of it, you will conflict with any future IC
  3.    * implementation that doesn't use explicit preference files.
  4.    */
  5.  
  6. pascal ICError ICGetConfigReference(ICInstance inst, ICConfigRefHandle ref);
  7.   /* Requires IC 1.2.
  8.    * You must specify a configuration before calling this routine.
  9.    * Returns a self-contained reference to the instance's current
  10.    * configuration.
  11.    * ref must be a valid non-nil handle and it will be resized to fit the
  12.    * resulting data.
  13.    */
  14.  
  15. pascal ICError ICSetConfigReference(ICInstance inst, ICConfigRefHandle ref, long flags);
  16.   /* Requires IC 1.2.
  17.    * It is illegal to call this routine inside a ICBegin/End pair.
  18.    * Reconfigures the instance using a configuration reference that was
  19.    * got using ICGetConfigReference reference. Set the
  20.    * icNoUserInteraction_bit in flags if you require that this routine
  21.    * not present a modal dialog. Other flag bits are reserved and should
  22.    * be set to zero.
  23.    * ref must not be nil.
  24.    */
  25.  
  26. pascal ICError ICSpecifyConfigFile(ICInstance inst, FSSpec *config);
  27.   /* It is illegal to call this routine inside a ICBegin/End pair.
  28.    * For use only by the IC application.
  29.    * If you call this routine yourself, you will conflict with any
  30.    * future IC implementation that doesn't use explicit preference files.
  31.    */
  32.  
  33. /* ***** Getting Information ***** */
  34.  
  35. pascal ICError ICGetSeed(ICInstance inst, long *seed);
  36.   /* You do not have to specify a configuration before calling this routine.
  37.    * You do not have to be inside an ICBegin/End pair to call this routine.
  38.    * Returns the current seed for the IC prefs database.
  39.    * This seed changes each time a non-volatile preference is changed.
  40.    * You can poll this to determine if any cached preferences change.
  41.    */
  42.  
  43. pascal ICError ICGetPerm(ICInstance inst, ICPerm *perm);
  44.   /* You do not have to specify a configuration before calling this routine.
  45.    * Returns the access permissions currently associated with this instance.
  46.    * While applications normally know what permissions they have,
  47.    * this routine is designed for use by override components.
  48.    */
  49.  
  50. pascal ICError ICDefaultFileName(ICInstance inst, Str63 name);
  51.   /* You do not have to specify a configuration before calling this routine.
  52.    * You do not have to be inside an ICBegin/End pair to call this routine.
  53.    * Returns the default file name for IC preference files.
  54.    * Applications should never need to call this routine.
  55.    * If you rely on information returned by this routine yourself,
  56.    * you may conflict with any future IC implementation that doesn't use
  57.    * explicit preference files.
  58.    * The component calls this routine to set up the default IC file name.
  59.    * This allows this operation to be intercepted by a component that has
  60.    * captured us. It currently gets it from the component resource file.
  61.    * The glue version is hardwired to "Internet Preferences".
  62.    */
  63.  
  64. pascal ICError ICGetComponentInstance(ICInstance inst, Ptr *component_inst);
  65.   /* Requires IC 1.2.
  66.    * You do not have to specify a configuration before calling this routine.
  67.    * You do not have to be inside an ICBegin/End pair to call this routine.
  68.    * Returns noErr and the connection to the IC component,
  69.    * if we're using the component.
  70.    * Returns badComponenInstance and nil if we're operating with glue.
  71.    * The component_inst parameter is a universal pointer to avoid
  72.    * us having to include Component.[ph] (which is not available under
  73.    * some development environments) in order to use IC.
  74.    */
  75.  
  76. /* ***** Reading and Writing Preferences ***** */
  77.  
  78. pascal ICError ICBegin(ICInstance inst, ICPerm perm);
  79.   /* You must specify a configuration before calling this routine.
  80.    * It is illegal to call this routine inside a ICBegin/End pair.
  81.    * Starting reading or writing multiple preferences.
  82.    * A call to this must be balanced by a call to ICEnd.
  83.    * Do not call WaitNextEvent between these calls.
  84.    * The perm specifies whether you intend to read or read/write.
  85.    * Only one writer is allowed per instance.
  86.    * Note that this may open resource files thdle(ICInstance inst, ConstStr255Param key, ICAttr attr, Handle prefh);
  87.   /* Requires IC 1.1.
  88.    * You must specify a configuration before calling this routine.
  89.    * If you are getting or setting multiple preferences, you should place
  90.    * these calls within an ICBegin/ICEnd pair.
  91.    * If you call this routine outside of such a pair, it implicitly
  92.    * calls ICBegin(inst, icReadWritePerm).
  93.    * Sets the preference specified by key from the IC database to the
  94.    * value contained in prefh.
  95.    * key must not be the empty string.
  96.    * If prefh is nil then the preference value is not set.
  97.    * If buf is not nil then the preference value is set to the data
  98.    * contained in it.
  99.    * If attr is ICattr_no_change then the preference attributes are not set.
  100.    * Otherwise the preference attributes are set to attr.
  101.    * Returns icPermErr if the previous ICBegin was passed icReadOnlyPerm.
  102.    * Returns icPermErr if current attr is locked, new attr is locked and prefh <> nil.
  103.    */
  104.  
  105. pascal ICError ICCountPref(ICInstance inst, long *count);
  106.   /* You must specify a configuration before calling this routine.
  107.    * You must be inside an ICBegin/End pair to call this routine.
  108.    * Counts the total number of preferences.
  109.    * If the routine returns an error, count is set to 0.
  110.    */
  111.  
  112. pascal ICError ICGetIndPref(ICInstance inst, long n, Str255 key);
  113.   /* You must specify a configuration before calling this routine.
  114.    * You must be inside an ICBegin/End pair to call this routine.
  115.    * Returns the key of the Nth preference.
  116.    * n must be positive.
  117.    * Returns icPrefNotFoundErr if n is greater than the total number of preferences.
  118.    * If the routine returns an error, key is undefined.
  119.    */
  120.  
  121. pascal ICError ICDeletePref(ICInstance inst, ConstStr255Param key);
  122.   /* You must specify a configuration before calling this routine.
  123.    * You must be inside an ICBegin/End pair to call this routine.
  124.    * Deletes the preference specified by key.
  125.    * key must not be the empty string.
  126.    * Returns icPrefNotFound if the preference specified by key is not present.
  127.    */
  128.  
  129. pascal ICError ICEnd(ICInstance inst);
  130.   /* You must specify a configuration before calling this routine.
  131.    * You must be inside an ICBegin/End pair to call this routine.
  132.    * Terminates a preference session, as started by ICBegin.
  133.    * You must have called ICBegin before calling this routine.
  134.    */
  135.  
  136. /* ***** User Interface Stuff ***** */
  137.  
  138. pascal ICError ICEditPreferences(ICInstance inst, ConstStr255Param key);
  139.   /* Requires IC 1.1.
  140.    * You must specify a configuration before calling this routine.
  141.    * You do not have to be inside an ICBegin/End pair to call this routine.
  142.    * Instructs IC to display the user interface associated with editing
  143.    * preferences and focusing on the preference specified by key.
  144.    * If key is the empty string then no preference should be focused upon.
  145.    * You must have specified a configuration before calling this routine.
  146.    * You do not need to call ICBegin before calling this routine.
  147.    * In the current implementation this launches the IC application
  148.    * (or brings it to the front) and displays the window containing
  149.    * the preference specified by key.
  150.    * It may have a radically different implementation in future
  151.    * IC systems.
  152.    */
  153.  
  154. /* ***** URL Handling ***** */
  155.  
  156. pascal ICError ICParseURL(ICInstance inst, ConstStr255Param hint, Ptr data, long len, long *selStart, long *selEnd, Handle url);
  157.   /* Requires IC 1.1.
  158.    * You must specify a configuration before calling this routine.
  159.    * You do not have to be inside an ICBegin/End pair to call this routine.
  160.    * Parses a URL out of the specified text and returns it in a canonical form
  161.    * in a handle.
  162.    * hint indicates the default scheme for URLs of the form "name@address".
  163.    * If hint is the empty string then URLs of that form are not allowed.
  164.    * data points to the start of the text. It must not be nil.
  165.    * len indicates the length of the text. It must be non-negative.
  166.    * selStart and selEnd should be passed in as the current selection of
  167.    * the text. This selection is given in the same m name) of an outgoing
  168.    * file and returns the most appropriate mappings database entry.
  169.    * entries must be a handle to a valid IC mappings database preference.
  170.    * The filename may be either the name of the outgoing file or
  171.    * the empty string.
  172.    * Returns icPrefNotFoundErr if no suitable entry found.
  173.    */
  174.  
  175. /* ----- Low Level Routines ----- */
  176.  
  177. pascal ICError ICCountMapEntries(ICInstance inst, Handle entries, long *count);
  178.   /* Requires IC 1.1.
  179.    * You must specify a configuration before calling this routine.
  180.    * You do not have to be inside an ICBegin/End pair to call this routine.
  181.    * Counts the number of entries in the mappings database.
  182.    * entries must be a handle to a valid IC mappings database preference.
  183.    * count is set to the number of entries.
  184.    */
  185.  
  186. pascal ICError ICGetIndMapEntry(ICInstance inst, Handle entries, long ndx, long *pos, ICMapEntry *entry);
  187.   /* Requires IC 1.1.
  188.    * You must specify a configuration before calling this routine.
  189.    * You do not have to be inside an ICBegin/End pair to call this routine.
  190.    * Gets the ndx'th entry in the mappings database.
  191.    * entries must be a handle to a valid IC mappings database preference.
  192.    * ndx must be in the range from 1 to the number of entries in the database.
  193.    * The value of pos is ignored on input. pos is set to the position of
  194.    * the ndx'th entry in the database and is suitable for passing back
  195.    * into ICSetMapEntry.
  196.    * Does not return any user data associated with the entry.
  197.    */
  198.  
  199. pascal ICError ICGetMapEntry(ICInstance inst, Handle entries, long pos, ICMapEntry *entry);
  200.   /* Requires IC 1.1.
  201.    * You must specify a configuration before calling this routine.
  202.    * You do not have to be inside an ICBegin/End pair to call this routine.
  203.    * Returns the entry located at position pos in the mappings database.
  204.    * entries must be a handle to a valid IC mappings database preference.
  205.    * pos should be 0 to get the first entry. To get the subsequent entries, add
  206.    * entry.total_size to pos and iterate.
  207.    * Does not return any user data associated with the entry.
  208.    */
  209.  
  210. pascal ICError ICSetMapEntry(ICInstance inst, Handle entries, long pos, ICMapEntry *entry);
  211.   /* Requires IC 1.1.
  212.    * You must specify a configuration before calling this routine.
  213.    * You do not have to be inside an ICBegin/End pair to call this routine.
  214.    * Sets the entry located at position pos in the mappings database.
  215.    * entries must be a handle to a valid IC mappings database preference.
  216.    * pos should be either a value returned from ICGetIndMapEntry or a value
  217.    * calculated using ICGetMapEntry.
  218.    * entry is a var parameter purely for stack space reasons. It is not
  219.    * modified in any way.
  220.    * Any user data associated with the entry is unmodified.
  221.    */
  222.  
  223. pascal ICError ICDeleteMapEntry(ICInstance inst, Handle entries, long pos);
  224.   /* Requires IC 1.1.
  225.    * You must specify a configuration before calling this routine.
  226.    * You do not have to be inside an ICBegin/End pair to call this routine.
  227.    * Deletes the mappings database entry at pos.
  228.    * entries must be a handle to a valid IC mappings database preference.
  229.    * pos should be either a value returned from ICGetIndMapEntry or a value
  230.    * calculated using ICGetMapEntry.
  231.    * Also deletes any user data associated with the entry.
  232.    */
  233.  
  234. pascal ICError ICAddMapEntry(ICInstance inst, Handle entries, ICMapEntry *entry);
  235.   /* Requires IC 1.1.
  236.    * You must specify a configuration before calling this routine.
  237.    * You do not have to be inside an ICBegin/End pair to call this routine.
  238.    * Adds an entry to the mappings database.
  239.    * entries must be a handle to a valid IC mappings database preference.
  240.    * The entry is added to the end of the entries database.
  241.    * No user data is added.
  242.    */
  243.  
  244.  
  245. /* •••End ICAPI.h••• */
  246.  
  247. #ifdef __cplusplus
  248. extern "C" {
  249. #endif
  250.  
  251.  
  252. #ifdef __cplusplus
  253. }
  254. #endif __cplusplus
  255.  
  256. #endif
  257.